package jmine.tec.report;

import java.util.Comparator;
import java.util.List;

import jmine.tec.report.cell.DataCell;
import jmine.tec.report.impl.SimpleDataRow;

/**
 * Esta interface representa uma linha com dados relativos à colunas. Uma linha pode ter linhas filhas. Uma linha tem uma lista de
 * DataCell's.
 * 
 * @author julien
 * @author pedro última modificação: 16/02/2007 Pedro e Julien
 */
public interface DataRow {

    /**
     * Devolve o Row parente (acima) caso exista.
     * 
     * @return o {@link DataRow} parente ou null
     */
    DataRow getParentRow();

    /**
     * Seta o Row parente.
     * 
     * @param parentRow {@link DataRow}
     */
    void setParentRow(DataRow parentRow);

    /**
     * Retorna a lista dos DataRow's filhos deste DataRow. Se não tiver nenhum DataRow filho deve retornar uma lista vazia.
     * 
     * @return List
     */
    List<? extends DataRow> getChildRows();

    /**
     * Adiciona um DataRow à lista de DataRows filhos. Se o argumento for null lança um NullPointerException.
     * 
     * @param row DataRow
     */
    void addChildRow(DataRow row);

    /**
     * Adiciona um List de DataRow's à lista de DataRows filhos. Se o argumento for null lança um NullPointerException.
     * 
     * @param row List
     */
    void addChildRows(List<? extends DataRow> row);

    /**
     * Remove um DataRow da lista de DataRows filhos. Se o argumento for null lança um NullPointerException.
     * 
     * @param row DataRow
     */
    void removeChildRow(DataRow row);

    /**
     * Retorna o DataRow com o índice especificado. Lança IndexOutOfBoundsException se o índice for inválido.
     * 
     * @param index int
     * @return DataRow
     */
    DataRow getChildRow(int index);

    /**
     * Retorna a lista dos DataCell's deste DataRow. Se não tiver nenhum DataCell deve retornar uma lista vazia.
     * 
     * @return List
     * @deprecated prefer {@link #getCell(int)} instead
     */
    @Deprecated
    List<? extends DataCell> getCells();

    /**
     * Adiciona um DataCell na lista de DataCell's. Se o argumento for null lança um NullPointerException.
     * 
     * @param cell DataCell
     */
    void addCell(DataCell cell);

    /**
     * Adiciona um List de DataCell's na lista de DataCell's. Se o argumento for null lança um NullPointerException.
     * 
     * @param cell List
     */
    void addCells(List<? extends DataCell> cell);

    /**
     * Remove um DataCell da lista de DataCell's. Se o argumento for null lança um NullPointerException.
     * 
     * @param cell DataCell
     */
    void removeCell(DataCell cell);

    /**
     * Devolve a quantidade de celulas nesta linha.
     * 
     * @return int
     */
    int getCellCount();

    /**
     * Retorna o DataCell com o índice especificado. Lança IndexOutOfBoundsException se o índice for inválido.
     * 
     * @param index int
     * @return DataCell
     */
    DataCell getCell(int index);

    /**
     * Gets the {@link DataCell} that represents the name of this row.
     * 
     * @return {@link DataCell}
     */
    DataCell getNameDataCell();

    /**
     * Retorna o nome associado à este DataRow
     * 
     * @return String
     */
    String getName();

    /**
     * Ordena os DataRows filhos deste DataRow usando o Comparator especificado.
     * 
     * @param comparator Comparator
     * @return {@link DataRow} uma copia deste data row
     */
    DataRow sort(Comparator<? super DataRow> comparator);

    /**
     * Retorna uma "visão" deste DataRow. Esta "visão" deve ser serializável e não deve conter referências para objetos do modelo.
     * 
     * @return DataRow
     */
    SimpleDataRow toView();

    /**
     * Verifica se esta row é uma folha, ou seja, se não tem filhas.
     * 
     * @return boolean
     */
    boolean isLeafRow();

    /**
     * Devolve as celulas 'folha'. Se esta coluna eh uma 'folha' ({@link #isLeafRow()}), devolve a celula com o indice dado. Caso contrario,
     * coleta as celulas filha das 'rows' filhas desta row.
     * 
     * @param index int
     * @return {@link DataCell}
     */
    List<DataCell> getLeafCellsWithIndex(int index);

    /**
     * Remove e devolve a celula com o indice dado
     * 
     * @param index int
     * @return {@link DataCell}
     */
    DataCell removeCellWithIndex(int index);

    /**
     * Remove todas as {@link DataCell}
     */
    void removeAllCells();

    /**
     * Devolve um {@link Iterable} sobre as datacell. Modificacoes no {@link Iterable} nao sao refletidas neste {@link DataRow}
     * 
     * @return {@link Iterable}
     */
    Iterable<? extends DataCell> dataCellIterable();

    /**
     * Devolve um {@link Iterable} sobre as {@link DataRow} filhas. Modificacoes no {@link Iterable} nao sao refletidas neste
     * {@link DataRow}
     * 
     * @return {@link Iterable}
     */
    Iterable<? extends DataRow> dataRowIterable();

    /**
     * Transforma
     * 
     * @param trans o {@link DataCellTransformation}
     * @return {@link DataRow}
     */
    DataRow transform(DataCellTransformation trans);

}
